home *** CD-ROM | disk | FTP | other *** search
/ The 640 MEG Shareware Studio 2 / The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO / basic / qbser15.zip / QBSERIAL.DOC < prev    next >
Text File  |  1990-03-23  |  22KB  |  505 lines
  1.  
  2.  
  3.  
  4.                       Serial I/O Routines for use with QuickBASIC
  5.  
  6.           This library will provide you with serial I/O communications
  7.           routines for use in QuickBASIC 4.x (with or without PDQ), and the
  8.           Microsoft Basic Compiler 7.x Professional Development System. No
  9.           longer will you be forced to use the poor communications support
  10.           provided by QB.  This program will allow you to control
  11.           communications ports 1 - 4 at speeds of up to 115200 baud. You will
  12.           no longer have problems with the DTR signal. It is left in the same
  13.           state it was in when before this driver is called, or it can be
  14.           controlled by your program. The serial driver includes XON/XOFF and
  15.           CTS handshaking. Serial input is interrupt driven, with incoming
  16.           XOFF flow control (if enabled) to prevent overrunning the input
  17.           buffer. These are the same serial I/O routines used in the User
  18.           Database System Doors "Query Door" and "Upload Door".
  19.  
  20.           The driver was written using Microsoft's QuickC version 2.01. This
  21.           driver can ONLY be used with QuickBASIC version 4.x and BC7.0 PDS.
  22.           The reason is that versions of QuickBASIC prior to 4.0 do not
  23.           support the extensive multi-language interface that QB4.x has (via
  24.           the DECLARE statement). It seems to work fine with BASCOM 6 also,
  25.           although I did have problems with BC6 when the entire QuickC
  26.           library (MLIBCE) was used for linking. Since only portions of the C
  27.           library are included here, the error seems to be eliminated.
  28.           Throughout this manual QBSERIAL or QB will be used to refer to both
  29.           QuickBASIC and the new Basic Compiler 7.0 PDS.
  30.  
  31.           Before the driver can be used, the following DECLARE statements
  32.           must be added to the beginning of your QB program:
  33.  
  34.           DECLARE SUB OpenComm CDECL ALIAS "_open_comm" (BYVAL Port%, BYVAL_
  35.                                Wlen%, BYVAL Parity%, BYVAL Baud&, BYVAL HS%) 
  36.           DECLARE SUB CloseComm CDECL ALIAS "_close_comm" () 
  37.           DECLARE FUNCTION WriteChar% CDECL (BYVAL Ascii%) 
  38.           DECLARE FUNCTION ReadChar% CDECL () 
  39.           DECLARE SUB Transmit CDECL ALIAS "_transmit_string" (addr$) 
  40.           DECLARE FUNCTION DataWaiting% CDECL ALIAS "_data_waiting" () 
  41.           DECLARE SUB ClearInputBuffer CDECL ALIAS "_clear_input_buffer" () 
  42.           DECLARE SUB CarrierDetect CDECL ALIAS "_carrier_detect_flag"_
  43.                                     (BYVAL OnOff%) 
  44.           DECLARE SUB CDtrap CDECL ALIAS "_trap_mode" (BYVAL OnOff%)
  45.           DECLARE FUNCTION CarrierLost% CDECL ALIAS "_carrier_state" ()
  46.           DECLARE SUB DTRcontrol CDECL ALIAS "_dtr" (BYVAL OnOff%)
  47.  
  48.           These declarations specify all the entry points into the serial
  49.           driver, They are in the include file QBSERIAL.DEC. DO NOT change
  50.           them or the driver may not function.
  51.  
  52.           Refer to the included sample programs SIMPLE.BAS & PCBDOOR.BAS,
  53.           they use most of the calls described below.
  54.  
  55.  
  56.  
  57.         QBSERIAL User Manual - V 1.5                               Page 1
  58.  
  59.  
  60.  
  61.                                   Port Initialization
  62.  
  63.           OpenComm Port%, Wordlen%, Parity%, Baudrate&, HS%
  64.  
  65.           Port%     an integer value of 0, 1, 2, 3, or 4. If the specified
  66.                     port is 1 to 4, the driver seizes the serial interrupt
  67.                     for this port (IRQ3 or 4). You must restore this
  68.                     interrupt vector before program termination (explained
  69.                     later). If the port is specified as ZERO the driver
  70.                     enters "LOCAL" mode. This allows you to call the driver
  71.                     with data, but the driver wont actually send anything.
  72.                     This is useful when working with "doors".
  73.  
  74.  
  75.           Wordlen%  an integer specifying the word length of the serial data.
  76.                     It has a value of 7 or 8.
  77.  
  78.           Parity%   an integer, 0 = NONE, 1 = ODD, 2 = EVEN.
  79.  
  80.           BaudRate& is a LONG INTEGER representing the desired baud rate.
  81.                     Valid numbers are 0, 300, 1200, 2400, 4800, 9600, 19200,
  82.                     38400, 57600, and 115200. The value you send is NOT
  83.                     checked and I assume you could generate crazy baud rates
  84.                     if desired. 115200 is the absolute maximum rate that can
  85.                     be generated. If you specify a baud rate of ZERO then the
  86.                     serial port is used AS-IS. The rate, word length, &
  87.                     parity are NOT changed. This is useful for door operation
  88.                     since the port is already initialized at the proper
  89.                     settings when you get control.
  90.  
  91.           HS%       an integer specifying the type of handshake you wish to
  92.                     use between the CPU and Modem (or destination device).
  93.                     Valid numbers are: 0 = NO handshake, 1 = XON/XOFF, 2 =
  94.                     CTS, 3 = XON/XOFF and CTS.
  95.  
  96.  
  97.  
  98.                                      Serial Output
  99.  
  100.           To send a string of data out the serial port, you use the
  101.           "Transmit" call as follows:
  102.  
  103.                Temp$ = "Transmit this..."
  104.                Transmit Temp$
  105.  
  106.                     or
  107.  
  108.                Transmit "Send this also...."
  109.  
  110.           If you want to transmit single characters, you can use the
  111.           "WriteChar" function. Transmit calls WriteChar to send the actual
  112.  
  113.         QBSERIAL User Manual - V 1.5                               Page 2
  114.  
  115.  
  116.           characters to the port. If you wish to use WriteChar, it has the
  117.           following format:
  118.  
  119.                Status% = WriteChar(Char%)
  120.  
  121.           Char% is the integer value of the character you want to send, it is
  122.           not a string. Status% is an integer returned by WriteChar, it is
  123.           NON-ZERO if the character was actually sent to the port, and ZERO
  124.           if the character WAS NOT SENT because of No Carrier. Please note
  125.           that WriteChar will loop indefinitely on CTS hold, XOFF hold, or
  126.           Transmit Buffer Busy. These loops will exit if carrier is lost
  127.           (unless carrier detection is disabled), and return a ZERO status%.
  128.           WriteChar gives you more low level control of the sending of
  129.           characters, but you must send each character separately and monitor
  130.           its status.
  131.  
  132.           The Transmit function monitors the status of its calls to WriteChar
  133.           and triggers QuickBASIC's User Event trap (UEVENT) if a failure
  134.           occurs. The UEVENT trap is used by default. You can disable the use
  135.           of this event trap in the event you already use the UEVENT trap for
  136.           something else. Therefore, by default, carrier loss detection in
  137.           your program is done with the ON UEVENT GOSUB/UEVENT ON statements.
  138.           The example programs show the use of this method. By default UEVENT
  139.           is also used for catching carrier loss on keyboard input. this is
  140.           described below.
  141.  
  142.  
  143.  
  144.                                       Serial Input
  145.  
  146.           Serial input is managed with three functions: DataWaiting,
  147.           ReadChar, & ClearInputBuffer. DataWaiting is used to test the input
  148.           buffer to see if any characters need to be read from it. ReadChar
  149.           is then called to get the characters. ClearInputBuffer flushes the
  150.           input buffer of any existing characters. Both example programs
  151.           contain a subroutine called "KeyboardInput" that demonstrates the
  152.           use of these calls. It also properly handles input from the local
  153.           and remote keyboards, and can be the routine you use in your
  154.           programs if you wish. Basically the procedure for reading the
  155.           remote keyboard (serial input) is as follows:
  156.  
  157.                IF DataWaiting THEN
  158.                     C$ = CHR$(ReadChar)
  159.                END IF
  160.  
  161.           The DataWaiting function also monitors the state of the carrier
  162.           detect signal and triggers, by default, the user event trap
  163.           (UEVENT) if carrier is lost. As you can see a singular trap routine
  164.           catches carrier loss on output as well as input. You will notice
  165.           that the "KeyboardInput" subroutine loops using DataWaiting, and as
  166.           such, carrier is constantly checked while waiting for input. If the
  167.  
  168.  
  169.         QBSERIAL User Manual - V 1.5                               Page 3
  170.  
  171.  
  172.           ReadChar function is called when no data is available (as indicated
  173.           by DataWaiting) a NULL character is returned.
  174.  
  175.           If XOFF/XON or BOTH is enabled, then the serial buffer will be
  176.           protected from overfills. When the buffer reaches 75% of capacity,
  177.           an XOFF will be sent on the serial output. When the buffer empties
  178.           out to 25% of capacity, an XON will be sent. The capacity of the
  179.           input buffer is 1024 bytes.
  180.  
  181.  
  182.  
  183.                                  Carrier Detect Control
  184.  
  185.           Implemented in version 1.1 is a function call to allow the calling
  186.           program to control if the driver senses carrier. The driver
  187.           defaults to carrier detection ON unless you implicitly turn it off.
  188.           The following call has been added to do this:
  189.  
  190.                CarrierDetect 0 [or] 1
  191.  
  192.           Specifying a ZERO turns carrier detection OFF. Even if you have the
  193.           UEVENT turned ON, no trap will occur if carrier is lost. Also, any
  194.           internal loops (such as XOFF wait) will NOT exit if carrier is
  195.           lost. Specifying a ONE turns carrier detection back ON.
  196.  
  197.           Examples for the use of this would be where "plain Jane" serial I/O
  198.           is required where no modem handshake signals are used (simple 3
  199.           wire EIA). Carrier detection must be disabled in this mode
  200.           otherwise no data is sent. Another use might be in a program that
  201.           dials out on a modem to initiate a connection. Obviously at the
  202.           start of the call there is no carrier, and detection must be turned
  203.           off in order to send data to the modem. After a connection is
  204.           established, then the carrier detect can turned on again by the
  205.           program. Most applications however will not even use this function
  206.           call, since carrier detection defaults to ON.
  207.  
  208.  
  209.  
  210.                                  Carrier Loss Detection
  211.  
  212.           As mentioned above, by default, the UEVENT trap is used to detect
  213.           when a loss of carrier occurs (assuming carrier detection is
  214.           enabled as explained above). Implemented in version 1.2 are two new
  215.           function calls that allow you to detect loss of carrier without
  216.           using the UEVENT trap. While I feel that using UEVENT is the
  217.           simplest way to catch a carrier loss in a program, it is possible
  218.           that UEVENT might need to be used by something else. The two
  219.           functions used for this purpose are:
  220.  
  221.           CDtrap 0 [or] 1
  222.  
  223.              and
  224.  
  225.         QBSERIAL User Manual - V 1.5                               Page 4
  226.  
  227.  
  228.  
  229.           X% = CarrierLost
  230.  
  231.           CDtrap needs to be used ONLY when UEVENT is used for another
  232.           purpose. Setting CDtrap to ZERO instructs the driver not to trip
  233.           the UEVENT flag in Basic if carrier is lost. As you can see if your
  234.           program uses UEVENT for some other purpose, you wouldn't want the
  235.           driver causing false interrupts (CDtrap 1 returns driver to
  236.           normal). If you do not plan to use UEVENT for carrier loss
  237.           detection, or for ANYTHING else, then you DO NOT have to set CDtrap
  238.           to zero. As long as you do not turn UEVENT ON in your program,
  239.           Basic will not respond to the UEVENT flag even if it was tripped.
  240.  
  241.           The other function call allows to you to 'poll' for the state of
  242.           carrier. the "CarrierLost" functions returns a value indicating if
  243.           carrier is present of not. CarrierLost returns a NON-ZERO value
  244.           when there is NO carrier, and a ZERO when there IS carrier.
  245.           CarrierLost is a real time function, it returns the current carrier
  246.           condition at the time of the call. This allows you to code simple
  247.           IF or DO loops to detect loss:
  248.  
  249.                IF CarrierLost THEN
  250.                     ..process carrier loss
  251.                END IF
  252.  
  253.           Do NOT confuse these two functions with the "CarrierDetect"
  254.           function described in the previous section. That function controls
  255.           whether CD is checked before sending data, and what to do if no CD
  256.           is present. CDtrap only controls whether UEVENT is to be tripped or
  257.           not, and CarrierLost only returns the current carrier state.
  258.  
  259.  
  260.  
  261.                                   Program Termination
  262.  
  263.           Since "OpenComm" seizes interrupt vectors, these vectors need to be
  264.           restored BEFORE your program ends. If you neglect to restore these
  265.           vectors, you are guaranteed a crash. The routine used to reset the
  266.           vectors is: CloseComm. Only use CloseComm if you specified a port
  267.           value of 1, 2, 3, or 4 on the OpenComm call. If you specified a
  268.           port value of ZERO (Local mode) the interrupt vectors are NOT
  269.           grabbed, and do not need to be reset. CloseComm also resets any
  270.           UART registers to their original value, it also resets the
  271.           programmable interrupt controller (8259 PIC) to its original
  272.           settings.
  273.  
  274.  
  275.  
  276.                                Data Terminal Ready (DTR)
  277.  
  278.           Everybody that has used QuickBASIC's OPEN COMn statement is very
  279.           familiar with the problems of the DTR signal. Apparently Microsoft
  280.  
  281.         QBSERIAL User Manual - V 1.5                               Page 5
  282.  
  283.  
  284.           felt that DTR would never be needed after a program terminates.
  285.           Anybody who has ever tried to write a door, or chain from one
  286.           program to another has cursed this decision at some time during
  287.           their programs development. This driver handles the DTR with a
  288.           different view. When you close the comm channel the DTR signal is
  289.           left in the same state it was when you opened the comm channel. For
  290.           door applications, this is a must. 
  291.  
  292.           Implemented at version 1.2 is a function call that allows your
  293.           program to control the DTR signal:
  294.  
  295.  
  296.           DTRcontrol 1 [or] 0           ' 0 = DTR OFF, 1 = DTR ON
  297.  
  298.           Additionally when you use DTRcontrol to change the state of the DTR
  299.           signal it also instructs the driver to leave it this way when the
  300.           CloseComm function is called. Remember that the driver leaves DTR
  301.           the way it found it when OpenComm was called. If you used some
  302.           other method to change DTR after OpenComm was called, it would
  303.           automatically return to that original state when you called
  304.           CloseComm. Therefor only DTRcontrol should be used if you wish to
  305.           change the state of DTR.
  306.  
  307.  
  308.                                  Cresent's PDQ Library
  309.  
  310.           An object module for use with PDQ is also included. This version is
  311.           intended to be used ONLY with QuickBASIC 4.x. Actually the PDQ
  312.           version is identical to the QB version. The only difference is that
  313.           the PDQ version has no calls to UEvent (since there is no UEvent
  314.           routine in PDQ). You could in fact use either version (QBSER.OBJ or
  315.           QBSERPQD.OBJ) with QB 4.x if you never wanted to use UEvent as your
  316.           carrier detect trap. If you select to use QBSERPDQ.OBJ, substitute
  317.           it for QBSER.OBJ in the following paragraphs.
  318.  
  319.  
  320.                                         Linking
  321.  
  322.           Since object modules are provided for both QB and BC7, you will
  323.           need to select which one to use for your program. The additional
  324.           library (SERIAL.LIB) only contains routines from the C library that
  325.           are required by the driver. The file QBSER.OBJ should be used for
  326.           programs compiled with QuickBASIC, and BC7SER.OBJ is to be used for
  327.           programs compiled with BC7 PDS. Typical link command lines would
  328.           look like this:
  329.  
  330.           Link yourprog qbser,,,serial;
  331.  
  332.                or
  333.  
  334.           Link yourprog bc7ser,,,serial;
  335.  
  336.  
  337.         QBSERIAL User Manual - V 1.5                               Page 6
  338.  
  339.  
  340.           An alternate way would be to add to the SERIAL.LIB the obj file you
  341.           will always use. This requires you to have the LIB program (which
  342.           comes with both versions of basic). To all the object file to the
  343.           lib, use the following command:
  344.  
  345.           Lib serial +qbser;
  346.  
  347.                or
  348.  
  349.           Lib serial +bc7ser;
  350.  
  351.           after doing this, you can link as follows:
  352.  
  353.           Link yourprog,,,serial;
  354.  
  355.           Remember that the library you modify can only be used with the
  356.           version of Basic whose object module you add.
  357.  
  358.  
  359.                                     Quick Libraries
  360.  
  361.           If you wish to develop programs from within the environment, you
  362.           will first need to create a Quick library using one of the object
  363.           modules (QBSER.OBJ or BC7SER.OBJ) and the SERIAL.LIB file. To
  364.           create a Quick lib for QuickBASIC 4.x, use the following Link
  365.           command:
  366.  
  367.                Link QBSER SERIAL.LIB,,,BQLB4x/q
  368.  
  369.           Where "BQLB4x" is one of the following: BQLB40.LIB, BQLB41.LIB, or
  370.           BQLB45.LIB. Use the one that came with your compiler. If you use
  371.           the wrong BQLB file you might get an "Invalid Format" error when
  372.           attempting to start QuickBASIC. QBSER.OBJ & SERIAL.LIB may also be
  373.           added to Quick Libraries containing other routines and OBJ's as
  374.           well.
  375.  
  376.           To create a Quick Library for use within QBX (BC7's environment)
  377.           use the following link command (be sure to use Link v5.05 that came
  378.           with BC7):
  379.  
  380.                Link BC7SER SERIAL.LIB,,,QBXQLB/q;
  381.  
  382.           Remember too, that you can also add BC7SER.OBJ & SERIAL.LIB to
  383.           Quicklibs containing other routines.
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.         QBSERIAL User Manual - V 1.5                               Page 7
  394.  
  395.  
  396.                                      Specifications
  397.  
  398.           The following port addresses and interrupts are used:
  399.  
  400.                Comm      Base Address        IRQ
  401.  
  402.                 1          3F8 hex            4
  403.                 2          2F8 hex            3
  404.                 3          3E8 hex            4
  405.                 4          2E8 hex            3
  406.  
  407.  
  408.  
  409.                                         Support
  410.  
  411.           I'm reachable in the Interlink Basic conference, or the number
  412.           below. I'll help there if you have questions. No other support is
  413.           necessary. Bugs will be tended to if required, and good suggestions
  414.           tend to be implemented.
  415.  
  416.           In the spirit of programmer to programmer I am not requesting any
  417.           compensation for the use of these routines other than you
  418.           acknowledge in your documentation that you are using them. If you
  419.           feel they are worth something and you want to send me something I
  420.           won't refuse it! If you are using them in a PCBoard door, a copy of
  421.           the door for our system would be a nice gesture!
  422.  
  423.           However, if you plan to use QBserial in a commercial product for
  424.           resale, please contact me first.
  425.  
  426.  
  427.                                       Source Code
  428.  
  429.           The source code for QBserial is now available. The source is ONLY
  430.           available by signing a license agreement. The source may be used
  431.           for internal use only. The source may not be distributed by you to
  432.           any other person, even if you make changes to it. Nor can the
  433.           resulting object code be sold or distributed. Modifications can
  434.           only be used in your end product, and without any type of royalty.
  435.           The license fee for the QBserial source code is $75.00. Please
  436.           contact me if you are interested.
  437.  
  438.                                       Jeff Sumberg
  439.                                 Sysop(2) - SailBoard BBS
  440.                                 Wayne, NJ, 201-831-8152
  441.  
  442.                                         [ or ]
  443.  
  444.                                         Box 212
  445.                                   Ringwood, NJ, 07456
  446.  
  447.  
  448.  
  449.         QBSERIAL User Manual - V 1.5                               Page 8
  450.  
  451.  
  452.                                  Changes and Revisions
  453.  
  454.           06/09/89  1.0       Initial Release
  455.  
  456.           06/21/89  1.1       Added carrier detection control. Calling
  457.                               program can turn detection off and on as
  458.                               desired. Necessary if data sending/receiving
  459.                               required if carrier isn't present.
  460.  
  461.           09/01/89  1.2       Fixed a bug in Readchar where 'extended'
  462.                               characters (ASCII 128 to 255) were causing an
  463.                               Illegal Function Call in the CHR$() conversion
  464.                               (because they were being returned as negative
  465.                               numbers). Extended character may now be
  466.                               received properly. Added three new functions:
  467.                               CDtrap, CarrierLost, and DTRcontrol.
  468.  
  469.                     1.3
  470.                     1.4       Un-released interim versions.
  471.  
  472.           03/24/90  1.5       Added support for Basic Compiler 7.0 PDS and
  473.                               PDQ. Added sections to manual about Linking,
  474.                               Source code availability, and updated section
  475.                               on Quicklibs. Separate object files now
  476.                               supplied for QB, BC7, and PDQ.
  477.  
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.         QBSERIAL User Manual - V 1.5                               Page 9